---
type: integration
title: '@astrojs/vercel'
description: 'Astro 프로젝트를 배포하기 위해 @astrojs/vercel 어댑터를 사용하는 방법을 알아보세요.'
sidebar:
  label: Vercel
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/vercel/'
category: adapter
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Since from '~/components/Since.astro';
import ReadMore from '~/components/ReadMore.astro'
import { Steps } from '@astrojs/starlight/components';

이 어댑터를 사용하면 Astro가 [서버 아일랜드](/ko/guides/server-islands/), [액션](/ko/guides/actions/), [세션](/ko/guides/sessions/)을 포함하여 [요청 시 렌더링되는 라우트 및 기능](/ko/guides/on-demand-rendering/)을 [Vercel](https://www.vercel.com)에 배포할 수 있습니다.

Astro를 정적 사이트 빌더로 사용하는 경우 추가 Vercel 서비스 (예: [Vercel Web Analytics](https://vercel.com/docs/analytics), [Vercel Image Optimization](https://vercel.com/docs/image-optimization))를 사용하는 경우에만 이 어댑터가 필요합니다. 그렇지 않으면 정적 사이트를 배포하는 데 어댑터가 필요하지 않습니다.

[Vercel 배포 가이드](/ko/guides/deploy/vercel/)에서 Astro 사이트를 배포하는 방법을 알아보세요.

## 왜 Astro Vercel인가?

[Vercel](https://www.vercel.com/)은 GitHub 저장소에 직접 연결하여 사이트를 호스팅할 수 있게 해주는 배포 플랫폼입니다. 이 어댑터는 Vercel을 통해 배포할 프로젝트를 준비하기 위해 Astro 빌드 프로세스를 향상시킵니다.

## 설치

Astro는 공식 통합을 설정을 자동화하기 위한 `astro add` 명령을 포함하고 있습니다. 원한다면, [수동으로 통합 설치](#수동-설치)할 수도 있습니다.

Astro 프로젝트의 요청 시 렌더링을 활성화하기 위해 다음 `astro add` 명령을 사용하여 Vercel 어댑터를 추가하세요. 이를 통해 `@astrojs/vercel`이 설치되고 `astro.config.mjs` 파일이 한번에 적절히 변경됩니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add vercel
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add vercel
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add vercel
  ```
  </Fragment>
</PackageManagerTabs>

이제 [페이지별로 요청 시 렌더링](/ko/guides/on-demand-rendering/#요청-시-렌더링-활성화)을 활성화하거나, [기본적으로 모든 페이지를 서버 렌더링](/ko/guides/on-demand-rendering/#server-모드)하도록 빌드 출력 구성을 `output: 'server'`로 설정할 수 있습니다.

### 수동 설치

먼저, 선호하는 패키지 관리자를 사용하여 프로젝트의 종속성에 `@astrojs/vercel` 어댑터를 추가합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/vercel
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/vercel
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/vercel
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 `astro.config.*` 파일에 어댑터를 추가합니다:

```js title="astro.config.mjs" ins={2, 6}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel(),
});
```

## 사용

<ReadMore>
  [Vercel에 프로젝트를 배포](/ko/guides/deploy/vercel/)하는 방법에 대해 자세히 알아보세요.
</ReadMore>

CLI (`vercel deploy`)를 사용하여 배포하거나, [Vercel 대시보드](https://vercel.com/)에서 새 레포지토리를 연결하여 배포할 수 있습니다. 또는 로컬에서 프로덕션 빌드를 생성할 수 있습니다.

```sh
astro build
vercel deploy --prebuilt
```

## 구성

이 어댑터를 구성하려면, `astro.config.mjs` 파일의 `vercel()` 함수 호출에 객체를 전달하세요.

### `webAnalytics`

<p>
**타입:** `VercelWebAnalyticsConfig`<br/>
**사용 가능한 모드:** Serverless, Static<br/>
<Since v="3.8.0" pkg="@astrojs/vercel" />
</p>

`@vercel/analytics@1.3.x` 이하 버전에서는 Astro 구성에서 `webAnalytics: { enabled: true }`를 설정하여 모든 페이지에 Vercel의 추적 스크립트를 주입할 수 있습니다.

`@vercel/analytics@1.4.0` 이상 버전에서는 대신 Vercel의 Analytics 컴포넌트를 사용하여 [Vercel 웹 애널리틱스](https://vercel.com/docs/concepts/analytics)를 활성화하세요.

```js title="astro.config.mjs" ins={7-9}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    webAnalytics: {
      enabled: true,
    },
  }),
});
```

### `imagesConfig`

<p>

**타입:** `VercelImageConfig`<br/>
**사용 가능한 모드:** Serverless, Static<br />
<Since v="3.3.0" pkg="@astrojs/vercel" />
</p>

[Vercel의 이미지 최적화 API](https://vercel.com/docs/concepts/image-optimization)에 대한 구성 옵션입니다. 지원되는 매개변수의 전체 목록은 대한 구성 옵션입니다. 지원되는 모든 매개변수에 대해서는 [Vercel의 이미지 구성 문서](https://vercel.com/docs/build-output-api/v3/configuration#images)를 참조하세요.

`domains` 및 `remotePatterns` 속성은 [Astro의 해당 `image` 설정](/ko/reference/configuration-reference/#이미지-옵션)을 통해 자동으로 채워집니다.

```js title="astro.config.mjs" ins={8-10}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imagesConfig: {
      sizes: [320, 640, 1280],
    },
  }),
});
```

### `imageService`

<p>

**타입:** `boolean`<br/>
**사용 가능한 모드:** Serverless, Static<br />
<Since v="3.3.0" pkg="@astrojs/vercel" />
</p>

활성화되면 Vercel 이미지 최적화 API에 의해 구동되는 [이미지 서비스](/ko/reference/image-service-reference/)가 자동으로 구성되고 프로덕션에서 사용됩니다. 개발 모드에서는 [`devImageService`](#devimageservice)에 지정된 이미지 서비스가 대신 사용됩니다.

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imageService: true,
  }),
});
```

```astro title="src/pages/index.astro"
---
import { Image } from 'astro:assets';
import astroLogo from '../assets/logo.png';
---

<!-- 이 컴포넌트는 -->
<Image src={astroLogo} alt="My super logo!" />

<!-- 다음 과 같은 HTML이 될 것입니다 -->
<img
  src="/_vercel/image?url=_astro/logo.hash.png&w=...&q=..."
  alt="My super logo!"
  loading="lazy"
  decoding="async"
  width="..."
  height="..."
/>
```

### `devImageService`

<p>

**타입:** `'sharp' | string`<br/>
**기본값:** `sharp`<br />
**사용 가능한 모드:** Serverless, Static<br />
<Since v="3.8.0" pkg="@astrojs/vercel" />
</p>

[imageService](#imageservice)가 활성화된 경우 개발모드에서 사용할 이미지 서비스를 구성할 수 있습니다. 이는 개발 기기에 Sharp의 종속성을 설치할 수는 없는 경우 Squoosh와 같은 다른 이미지 서비스를 사용하여 개발 환경에서 이미지를 미리 볼 수 있으므로 유용할 수 있습니다. 빌드는 영향을 받지 않고 항상 Vercel의 이미지 최적화를 사용합니다.

Astro의 내장 서비스 대신 사용자 정의 이미지 서비스를 사용하기 위해 임의의 값으로 설정할 수도 있습니다.

```js title="astro.config.mjs" ins={7-8}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    imageService: true,
    devImageService: 'sharp',
  }),
});
```

### `isr`

<p>

**타입:** `boolean | VercelISRConfig`<br/>
**기본값:** `false`<br />
**사용 가능한 모드:** Serverless<br />
<Since v="7.2.0" pkg="@astrojs/vercel" />
</p>

첫 번째 요청 후 사전 렌더링된 페이지와 동일한 방식으로 주문형 렌더링된 페이지를 캐시하는 [ISR (증분 정적 재생성)](https://vercel.com/docs/incremental-static-regeneration) 함수로 프로젝트를 배포할 수 있습니다.

이 기능을 활성화하려면 `astro.config.mjs` 파일의 Vercel 어댑터 구성에서 `isr`을 true로 설정하세요.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    isr: true,
  }),
});
```

ISR 함수 요청에는 정적 모드의 [요청](/ko/reference/api-reference/#request)과 유사한 검색 매개변수가 포함되지 않습니다.

#### ISR 캐시 무효화

기본적으로 ISR 함수는 배포 기간 동안 캐시됩니다. 만료 시간을 설정하거나 캐싱에서 특정 경로를 완전히 제외하여 캐싱을 추가로 제어할 수 있습니다.

##### 시간 기반 무효화

`expiration` 값을 초 단위로 구성하여 경로를 캐시하는 시간을 변경할 수 있습니다.

```js title="astro.config.mjs" {7-10}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    isr: {
      // 첫 번째 요청 시 모든 페이지를 캐시하고 1일 동안 저장합니다.
      expiration: 60 * 60 * 24,
    },
  }),
});
```

##### 캐싱에서 경로 제외

Vercel의 [초안 모드](https://vercel.com/docs/build-output-api/v3/features#draft-mode) 또는 [주문형 증분형 정적 재생성 (ISR)](https://vercel.com/docs/build-output-api/v3/features#on-demand-incremental-static-regeneration-isr)을 구현하려면 bypass 토큰을 생성하고 이를 캐싱에서 제외할 경로와 함께 `isr` 구성에 제공할 수 있습니다.

```js title="astro.config.mjs" {6-15}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  adapter: vercel({
    isr: {
      // 여러분이 생성하는 무작위 비밀 문자열입니다.
      bypassToken: '005556d774a8',
      // 항상 최신 상태로 제공되는 경로입니다.
      exclude: [
        '/preview', 
        '/auth/[page]',
        /^\/api\/.+/ // `@astrojs/vercel@v8.1.0`부터 정규 표현식이 지원됩니다.
      ]
    },
  }),
});
```

### `includeFiles`

<p>

**타입:** `string[]`<br/>
**사용 가능한 모드:** Serverless
</p>

파일을 함수와 번들링하기 위해 이 속성을 사용합니다. 이는 누락된 파일을 발견했을 때 유용합니다.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    includeFiles: ['./my-data.json'],
  }),
});
```

### `excludeFiles`

<p>

**타입:** `string[]`<br/>
**사용 가능한 모드:** Serverless
</p>

이 속성을 사용하면 포함된 파일을 번들링 프로세스에서 제외할 수 있습니다.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    excludeFiles: ['./src/some_big_file.jpg'],
  }),
});
```

### `maxDuration`

<p>

**타입:** `number`<br/>
**사용 가능한 모드:** Serverless
</p>

이 속성을 사용하여 서버리스 함수가 타임아웃되기 전에 실행될 수 있는 최대 시간(초)을 연장하거나 제한할 수 있습니다. 계정 플랜의 기본 및 최대 한도는 [Vercel 문서](https://vercel.com/docs/functions/serverless-functions/runtimes#maxduration)를 참조하세요.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    maxDuration: 60,
  }),
});
```

### `skewProtection`

<p>

**타입:** `boolean`<br/>
**사용 가능한 모드:** Serverless<br />
<Since pkg="@astrojs/vercel" v="7.6.0" />
</p>

이 속성을 사용하여 [Vercel Skew protection](https://vercel.com/docs/deployments/skew-protection) (Vercel Pro 및 Enterprise 계정에서 사용 가능)을 활성화합니다.

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
// ...
  adapter: vercel({
    skewProtection: true
  }),
});
```

### Vercel Edge Functions에서 Astro 미들웨어 실행

`@astrojs/vercel` 어댑터는 코드 베이스의 Astro 미들웨어에서 [에지 함수](https://vercel.com/docs/functions/edge-functions)를 생성할 수 있습니다. `edgeMiddleware`가 활성화되면 에지 함수는 정적 자산, 사전 렌더링된 페이지, 주문형 렌더링된 페이지를 포함한 모든 요청에 ​​대해 미들웨어 코드를 실행합니다.

주문형 렌더링된 페이지의 경우 `context.locals` 객체는 JSON을 사용하여 직렬화되고 렌더링을 수행하는 서버리스 함수의 헤더로 전송됩니다. 보안 조치로서 서버리스 함수는 생성된 에지 함수에서 발생하지 않는 한 `403 Forbidden` 응답이 포함된 요청 처리를 거부합니다.

이는 선택적 기능입니다. 활성화하려면 `edgeMiddleware`를 `true`로 설정하세요.

```js title="astro.config.mjs" "edgeMiddleware: true"
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  // ...
  adapter: vercel({
    edgeMiddleware: true,
  }),
});
```

에지 미들웨어는 `ctx.locals.vercel.edge`로 Vercel의 [`RequestContext`](https://vercel.com/docs/functions/edge-middleware/middleware-api#requestcontext)에 액세스할 수 있습니다. TypeScript를 사용하는 경우 `EdgeLocals`를 사용하기 위해 `src/env.d.ts` 파일을 업데이트하여 [적절한 타입](/ko/guides/typescript/#전역-타입-확장하기)을 얻을 수 있습니다.

```ts
type EdgeLocals = import('@astrojs/vercel').EdgeLocals

declare namespace App {
  interface Locals extends EdgeLocals {
    // ...
  }
}
```

### 세션

[Astro 세션 API](/ko/guides/sessions/)를 사용하면 요청 간에 사용자 데이터를 쉽게 저장할 수 있습니다. 이는 사용자 데이터 및 설정, 쇼핑 카트, 인증 자격 증명 등에 활용될 수 있습니다. 쿠키 저장소와 달리 데이터 크기에 제한이 없으며, 다른 기기에서도 복원할 수도 있습니다.

Vercel에서 세션을 사용할 때는 세션 스토리지를 위한 [드라이버를 구성](/ko/reference/configuration-reference/#sessiondriver)해야 합니다. [Vercel 마켓플레이스](https://vercel.com/marketplace?category=storage)에서 스토리지 제공업체를 설치할 수 있습니다.

예를 들어, [Redis 통합](https://vercel.com/marketplace?category=storage&search=redis)을 설치하고 데이터베이스를 사이트에 연결했다면 다음을 수행하세요.

<Steps>

1. `ioredis` 패키지를 설치합니다.
   <PackageManagerTabs>
     <Fragment slot="npm">
     ```sh
     npm install ioredis
     ```
     </Fragment>
     <Fragment slot="pnpm">
     ```sh
     pnpm install ioredis
     ```
     </Fragment>
     <Fragment slot="yarn">
     ```sh
     yarn add ioredis
     ```
     </Fragment>
   </PackageManagerTabs>

2. [Vercel CLI](https://vercel.com/docs/cli)를 사용하여 환경 변수를 로드합니다.

   ```sh
   vercel env pull .env.local
   ```
   이렇게 하면 로컬 개발 시 Redis 데이터베이스에 연결하는 데 필요한 환경 변수를 담은 `.env.local` 파일이 프로젝트 루트에 생성됩니다.

3. 세션 드라이버를 구성합니다.

    ```js title="astro.config.mjs" ins={6-11}
    import { defineConfig } from 'astro/config';
    import vercel from '@astrojs/vercel';

    export default defineConfig({
      adapter: vercel(),
      session: {
        driver: 'redis',
        options: {
          url: process.env.REDIS_URL,
        },
      },
    });
    ```

</Steps>

### Node.js 버전 지원

`@astrojs/vercel` 어댑터는 Astro 프로젝트를 Vercel에 배포하기 위한 특정 Node.js 버전을 지원합니다. Vercel에서 지원하는 Node.js 버전을 보려면 프로젝트의 Settings 탭을 클릭하고 "Node.js Version" 섹션까지 아래로 스크롤하세요.

[Vercel 문서](https://vercel.com/docs/functions/serverless-functions/runtimes/node-js#default-and-available-versions)를 참조하여 자세히 알아보십시오.

## 실험적 기능

다음 기능들도 사용 가능하지만, 향후 업데이트에서 대규모 변경 (Breaking Changes)이 발생할 수 있습니다. 프로젝트에서 이 기능을 사용 중이라면 업데이트를 위해 [`@astrojs/vercel` 변경 로그](https://github.com/withastro/astro/tree/main/packages/integrations/vercel/CHANGELOG.md)를 주의 깊게 확인하세요.

### `experimentalStaticHeaders`

<p>
**타입:** `boolean`<br/>
**기본값:** `false`<br />
**지원 모드:** Serverless <br/>
<Since pkg="@astrojs/vercel" v="8.2.0" />
</p>

Vercel 구성에서 사전 렌더링된 페이지에 대한 사용자 정의 헤더를 지정할 수 있습니다.

이 기능이 활성화되면, Astro 기능 (예: 콘텐츠 보안 정책)에서 제공하는 경우 어댑터는 [정적 헤더를 `vercel.json` 파일](https://vercel.com/docs/project-configuration#headers)에 저장합니다.

예를 들어, [실험적인 콘텐츠 보안 정책](/ko/reference/experimental-flags/csp/)이 활성화된 경우, `<meta>` 요소를 생성하는 대신 `experimentalStaticHeaders`를 사용하여 CSP `headers`를 Vercel 구성에 추가할 수 있습니다.

```js title="astro.config.mjs" {9}
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: vercel({
    experimentalStaticHeaders: true 
  })
});
```

[astro-integration]: /ko/guides/integrations-guide/
